<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 8.1</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="8.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="8.2.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P1">Part I. The Language</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#8">Chapter 8. Compilation, Execution, and Errors</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><a name="require"><h2>8.1 &ndash; The <code>require</code> Function</h2></a>

<p>Lua offers a higher-level function to load and run libraries,
called <code>require</code>.
Roughly, <code>require</code> does the same job as <code>dofile</code>,
but with two important differences.
First, <code>require</code> searches for the file in a path;
second, <code>require</code> controls whether a file has already been run
to avoid duplicating the work.
Because of these features,
<code>require</code> is the preferred function in Lua for loading libraries.

<p>The path used by <code>require</code> is a little different from
typical paths.
Most programs use paths as a list of directories wherein to search
for a given file.
However, ANSI C (the abstract platform where Lua runs)
does not have the concept of directories.
Therefore, the path used by <code>require</code> is a list of <em>patterns</em>,
each of them specifying an alternative way to transform
a virtual file name (the argument to <code>require</code>)
into a real file name.
More specifically,
each component in the path is a file name containing
optional interrogation marks.
For each component, <code>require</code> replaces each `<code>?</code>&acute; by the virtual
file name and checks whether there is a file with that name;
if not, it goes to the next component.
The components in a path are separated by semicolons
(a character seldom used for file names in most operating systems).
For instance, if the path is
<pre>
    ?;?.lua;c:\windows\?;/usr/local/lua/?/?.lua
</pre>
then the call <code>require"lili"</code> will try to open
the following files:
<pre>
    lili
    lili.lua
    c:\windows\lili
    /usr/local/lua/lili/lili.lua
</pre>
The only things that <code>require</code> fixes is
the semicolon (as the component separator) and the interrogation mark;
everything else (such as directory separators or file extensions)
is defined in the path.

<p>To determine its path,
<code>require</code> first checks the global variable <code>LUA_PATH</code>.
If the value of <code>LUA_PATH</code> is a string,
that string is the path.
Otherwise, <code>require</code> checks the environment variable <code>LUA_PATH</code>.
Finally, if both checks fail,
<code>require</code> uses a fixed path
(typically <code>"?;?.lua"</code>, although it is easy to change that when
you compile Lua).

<p>The other main job of <code>require</code> is to avoid loading the same
file twice.
For that purpose, it keeps a table with the names of all loaded files.
If a required file is already in the table,
<code>require</code> simply returns.
The table keeps the virtual names of the loaded files,
not their real names.
Therefore, if you load the same file with two different virtual names,
it will be loaded twice.
For instance,
the command <code>require"foo"</code> followed by <code>require"foo.lua"</code>,
with a path like <code>"?;?.lua"</code>,
will load the file <code>foo.lua</code> twice.
You can access this control table through the
global variable <code>_LOADED</code>.
Using this table, you can check which files have been loaded;
you can also fool <code>require</code> into running a file twice.
For instance, after a successful <code>require"foo"</code>,
<code>_LOADED["foo"]</code> will not be <B>nil</B>.
If you then assign <B>nil</B> to <code>_LOADED["foo"]</code>,
a subsequent <code>require"foo"</code> will run the file again.

<p>A component does not need to have interrogation marks;
it can be a fixed file name,
such as the last component in the following path:
<pre>
    ?;?.lua;/usr/local/default.lua
</pre>
In this case, whenever <code>require</code> cannot find
another option, it will run this fixed file.
(Of course, it only makes sense to have a fixed component as
the last component in a path.)
Before <code>require</code> runs a chunk,
it defines a global variable <code>_REQUIREDNAME</code> containing the
virtual name of the file being required.
We can use these facilities to extend the functionality of <code>require</code>.
In an extreme example,
we may set the path to something like <code>"/usr/local/lua/newrequire.lua"</code>,
so that every call to <code>require</code> runs <code>newrequire.lua</code>,
which can then use the value of
<code>_REQUIREDNAME</code> to actually load the required file.

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="8.2.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

